{smcl}
{* *! version 0.02 31-OCT-2018}{...}
{viewerjumpto "Title" "rdsampsi##title"}{...}
{viewerjumpto "Syntax" "rdsampsi##syntax"}{...}
{viewerjumpto "Description" "rdsampsi##description"}{...}
{viewerjumpto "Options" "rdsampsi##options"}{...}
{viewerjumpto "Examples" "rdsampsi##examples"}{...}
{viewerjumpto "Stored results" "rdsampsi##stored_results"}{...}
{viewerjumpto "References" "rdsampsi##refs"}{...}
{viewerjumpto "Authors" "rdsampsi##authors"}{...}
{viewerjumpto "Also see" "rdsampsi##also_see"}{...}
{cmd:help rdsampsi}{right: ({browse "https://doi.org/10.1177/1536867X19830919":SJ19-1: st0554})}
{hline}

{marker title}{...}
{title:Title}

{p2colset 5 17 19 2}{...}
{p2col:{cmd:rdsampsi} {hline 2}}Sample-size selection based on power
calculations for regression-discontinuity designs using robust bias-corrected
local polynomial inference{p_end}


{marker syntax}{...}
{title:Syntax}

{p 8 16 2}{cmd:rdsampsi} {it:depvar} {it:runvar} {ifin} 
[{cmd:,} 
{cmd:c(}{it:#}{cmd:)} 
{cmd:tau(}{it:#}{cmd:)} 
{cmd:alpha(}{it:#}{cmd:)}
{cmd:beta(}{it:#}{cmd:)} 
{cmd:{opt ns:amples}(}{it:# # # #}{cmd:)} 
{cmd:samph(}{it:# #}{cmd:)}
{cmd:all}
{cmd:plot} 
{cmd:graph_range(}{it:# #}{cmd:)} 
{cmd:graph_step(}{it:#}{cmd:)} 
{cmd:graph_options(}{it:graph_opt}{cmd:)} 
{cmd:bias(}{it:# #}{cmd:)}
{cmd:{opt var:iance}(}{it:# #}{cmd:)}
{cmd:nratio(}{it:#}{cmd:)}
{cmd:init_cond(}{it:#}{cmd:)}
{cmd:covs(}{it:covars}{cmd:)}
{cmd:deriv(}{it:dvalue}{cmd:)}
{cmd:p(}{it:#}{cmd:)} 
{cmd:q(}{it:#}{cmd:)}
{cmd:h(}{it:hvalueL hvalueR}{cmd:)} 
{cmd:b(}{it:bvalueL bvalueR}{cmd:)}
{cmd:rho(}{it:#}{cmd:)}
{cmd:fuzzy(}{it:fuzzyvar} [{cmd:sharpbw}]{cmd:)}
{cmd:kernel(}{it:kernelfn}{cmd:)}
{cmd:bwselect(}{it:bwmethod}{cmd:)}
{cmd:vce(}{it:vcemethod}{cmd:)}
{cmd:scalepar(}{it:#}{cmd:)}
{cmd:scaleregul(}{it:#}{cmd:)}]{p_end}


{marker description}{...}
{title:Description}

{pstd}
{cmd:rdsampsi} provides sample-size selection based on power calculations in
regression-discontinuity (RD) designs using conventional and robust
bias-corrected local polynomial methods.  The companion command is 
{helpb rdpow} for power calculations.{p_end}

{pstd}
A detailed introduction to this command is given in Cattaneo, Titiunik, and
Vazquez-Bare (2019).  Companion {browse "www.r-project.org":R} functions are
also available 
{browse "https://sites.google.com/site/rdpackages/rdpower":here}.

{pstd}
This command uses the Stata (and R) package {helpb rdrobust:rdrobust} for
underlying calculations.  See Calonico, Cattaneo, and Titiunik (2014) and
Calonico et al. (2017) for more details.{p_end}

{pstd}
Related Stata and R packages useful for inference in RD designs are described
at the following website:
{browse "https://sites.google.com/site/rdpackages/":https://sites.google.com/site/rdpackages/}.


{marker options}{...}
{title:Options}

{phang}
{cmd:c(}{it:#}{cmd:)} specifies the RD cutoff.  The default is {cmd:c(0)}.

{phang}
{cmd:tau(}{it:#}{cmd:)} specifies the treatment effect under the alternative
at which the power function is evaluated.  The default is half the standard
deviation of the outcome for the untreated group.{p_end}

{phang}
{cmd:alpha(}{it:#}{cmd:)} specifies the significance level for the power
function.  The default is {cmd:alpha(0.05)}.{p_end}

{phang}
{cmd:beta(}{it:#}{cmd:)} specifies the desired power.  The default is
{cmd:beta(0.8)}.{p_end}

{phang}
{cmd:nsamples(}{it:# # # #}{cmd:)}  sets the total sample size to the left,
sample size to the left inside the bandwidth, total sample size to the right,
and sample size to the right of the cutoff inside the bandwidth to calculate
the variance when the running variable is not specified.  By default, the
values are calculated using the running variable.{p_end}

{phang}
{cmd:samph(}{it:# #}{cmd:)} sets the bandwidths at each side of the cutoff for
power calculation.  The first number is the bandwidth to the left of the
cutoff, and the second number is the bandwidth to the right.  The default
values are the bandwidths used by {cmd:rdrobust}.{p_end}

{phang}
{cmd:all} displays the power using the conventional variance estimator and the
robust bias-corrected one.{p_end}

{phang}
{cmd:plot} plots the power function using the robust bias-corrected standard
error from {cmd:rdrobust}.  If {cmd:all} is specified, the conventional power
function is also plotted.{p_end}

{phang}
{cmd:graph_range(}{it:# #}{cmd:)} specifies the range of the plot when the
{cmd:plot} option is used.  The default range is [-1.5*tau ; 1.5*tau].{p_end}

{phang}
{cmd:graph_step(}{it:#}{cmd:)} specifies the step increment of the plot when
the {cmd:plot} option is used.  The default is
{cmd:graph_step(0.2*}{it:range}{cmd:)}.{p_end}

{phang}
{cmd:graph_options(}{it:graph_opt}{cmd:)} specifies the graph options (title,
axes titles, etc.) to be passed to the plot when the {cmd:plot} option is
used.{p_end}

{phang}
{cmd:bias(}{it:# #}{cmd:)} allows the user to set bias to the left and right
of the cutoff.  By default, the biases are estimated using {cmd:rdrobust}.

{phang}
{cmd:variance(}{it:# #}{cmd:)} allows the user to set variance to the left and
right of the cutoff.  By default, the variances are estimated using
{cmd:rdrobust}.

{phang}
{cmd:nratio(}{it:#}{cmd:)} specifies the proportion of treated units in the
window.  The default is the ratio of the standard deviation of the treated to
the sum of the standard deviations for treated and controls.{p_end}

{phang}
{cmd:init_cond(}{it:#}{cmd:)} sets the initial condition for the
Newton-Raphson algorithm that finds the sample size.  The default is the
number of observations in the sample with nonmissing values of the outcome and
running variable.{p_end}

{pstd}
The following options are passed directly to {cmd:rdrobust}:

{phang}
{cmd:covs(}{it:covars}{cmd:)} specifies additional covariates to be used for
estimation and inference.{p_end}

{phang}
{cmd:deriv(}{it:dvalue}{cmd:)} specifies the order of the derivative of the
regression functions to be estimated.  The default is {cmd:deriv(0)} (sharp RD
or fuzzy RD if {cmd:fuzzy()} is also specified).  Setting {cmd:deriv(1)}
results in estimation of a kink RD design (up to scale) or fuzzy-kink RD if
{cmd:fuzzy()} is also specified.

{phang}
{cmd:p(}{it:#}{cmd:)} specifies the order of the local polynomial to be used
to construct the point estimator.  The default is {cmd:p(1)} (local linear
regression).

{phang}
{cmd:q(}{it:#}{cmd:)} specifies the order of the local polynomial to be used
to construct the bias correction.  The default is {cmd:q(2)} (local quadratic
regression).

{phang}
{cmd:h(}{it:hvalueL hvalueR}{cmd:)} specifies the main bandwidth, h, to be
used on the left and on the right of the cutoff, respectively.  If only one
value is specified, then this value is used on both sides.  By default, the
bandwidth or bandwidths h are computed by the companion command 
{helpb rdbwselect}.

{phang}
{cmd:b(}{it:bvalueL bvalueR}{cmd:)} specifies the bias bandwidth, b, to be
used on the left and on the right of the cutoff, respectively.  If only one
value is specified, then this value is used on both sides.  By default, the
bandwidth or bandwidths b are computed by the companion command 
{helpb rdbwselect}.

{phang}
{cmd:rho(}{it:#}{cmd:)} specifies the value of rho so that the bias bandwidth,
b, equals b=h/rho.  The default is {cmd:rho(1)} if h is specified but b is
not.

{phang}
{cmd:fuzzy(}{it:fuzzyvar} [{cmd:sharpbw}]{cmd:)} specifies the treatment
status variable used to implement fuzzy RD estimation (or fuzzy-kink RD if
{cmd:deriv(1)} is also specified).  The default is sharp RD design.  If the
{cmd:sharpbw} option is set, the fuzzy RD estimation is performed using a
bandwidth selection procedure for the sharp RD model.  This option is
automatically selected if there is perfect compliance at either side of the
threshold.

{phang}
{cmd:kernel(}{it:kernelfn}{cmd:)} specifies the kernel function used to
construct the local polynomial estimators.  {it:kernelfn} may be 
{opt tri:angular}, {opt epa:nechnikov}, or {opt uni:form}.  The default is
{cmd:kernel(triangular)}.{p_end}

{phang}
{cmd:bwselect(}{it:bwmethod}{cmd:)} specifies the bandwidth selection
procedure to be used.  By default, it computes both h and b unless rho is
specified, in which case it computes only h and sets b=h/rho.  For details on
implementation, see Calonico, Cattaneo, and Titiunik (2014), Calonico,
Cattaneo, and Farrell (2018), Calonico et al. (2017), and the companion
software articles.  {it:bwmethod} may be one of the following:

{phang2}
{opt mserd} specifies one common mean squared error (MSE)-optimal bandwidth
selector for the RD treatment-effect estimator.  This is the default.{p_end}

{phang2}
{opt msetwo} specifies two MSE-optimal bandwidth selectors (below and above
the cutoff) for the RD treatment-effect estimator.{p_end}

{phang2}
{opt msesum} specifies one common MSE-optimal bandwidth selector for the sum
of regression estimates (as opposed to the difference thereof).{p_end}

{phang2}
{opt msecomb1} specifies min({opt mserd}, {opt msesum}).{p_end}

{phang2}
{opt msecomb2} specifies the median({opt msetwo}, {opt mserd}, {opt msesum})
for each side of the cutoff separately.{p_end}

{phang2}
{opt cerrd} specifies one common coverage error-rate (CER)-optimal bandwidth
selector for the RD treatment-effect estimator.{p_end}

{phang2}
{opt certwo} specifies two CER-optimal bandwidth selectors (below and above
the cutoff) for the RD treatment-effect estimator.{p_end}

{phang2}
{opt cersum} specifies one common CER-optimal bandwidth selector for the sum
of regression estimates (as opposed to the difference thereof).{p_end}

{phang2}
{opt cercomb1} specifies min({opt cerrd}, {opt cersum}).{p_end}

{phang2}
{opt cercomb2} specifies the median({opt certwo}, {opt cerrd}, {opt cersum})
for each side of the cutoff separately.{p_end}

{phang}
{cmd:vce(}{it:vcemethod}{cmd:)} specifies the procedure used to compute the
variance-covariance matrix estimator.  {it:vcemethod} may be one of the
following:

{phang2}
{cmd:nn} [{it:nnmatch}] specifies a heteroskedasticity-robust nearest-neighbor
variance estimator with {it:nnmatch} indicating the minimum number of
neighbors to be used.  The default is {cmd:vce(nn 3)}.

{phang2}
{cmd:hc0} specifies a heteroskedasticity-robust plugin residuals variance
estimator without weights.{p_end}

{phang2}
{cmd:hc1} specifies a heteroskedasticity-robust plugin residuals variance
estimator with {cmd:hc1} weights.{p_end}

{phang2}
{cmd:hc2} specifies a heteroskedasticity-robust plugin residuals variance
estimator with {cmd:hc2} weights.{p_end}

{phang2}
{cmd:hc3} specifies a heteroskedasticity-robust plugin residuals variance
estimator with {cmd:hc3} weights.{p_end}

{phang2}
{cmd:nncluster} {it:clustervar} [{it:nnmatch}] specifies a cluster-robust
nearest-neighbor variance estimator with {it:clustervar} indicating the
cluster ID variable and {it:nnmatch} indicating the minimum number of
neighbors to be used.{p_end}

{phang2}
{cmd:cluster} {it:clustervar} specifies a cluster-robust plugin residuals
variance estimator with degrees-of-freedom weights and {it:clustervar}
indicating the cluster ID variable.{p_end}

{phang}
{cmd:scalepar(}{it:#}{cmd:)} specifies the scaling factor for the RD parameter
of interest.  This option is useful when the population parameter of interest
involves a known multiplicative factor (for example, sharp kink RD).  The
default is {cmd:scalepar(1)} (no scaling).

{phang}
{cmd:scaleregul(}{it:#}{cmd:)} specifies the scaling factor for the
regularization term added to the denominator of the bandwidth selectors.
Setting {cmd:scaleregul(0)} removes the regularization term from the bandwidth
selectors.  The default is {cmd:scaleregul(1)}.{p_end}

		
{marker examples}{...}
{title:Examples: Cattaneo, Frandsen, and Titiunik (2015) incumbency data}

{pstd}
Setup{p_end}
{phang2}{cmd:. use rdpower_senate.dta}{p_end}

{pstd}
Sample-size calculation against an alternative hypothesis of tau = 5{p_end}
{phang2}{cmd:. rdsampsi demvoteshfor2 demmv, tau(5)}{p_end}

{pstd}
Sample-size calculation with covariates{p_end}
{phang2}{cmd:. rdsampsi demvoteshfor2 demmv, tau(5) covs(population dopen dmidterm)}{p_end}

{pstd}
Sample-size calculation with user-specified bandwidths{p_end}
{phang2}{cmd:. rdsampsi demvoteshfor2 demmv, tau(5) h(16 18) b(18 20)}{p_end}

{pstd}
Sample-size calculation with user-specified options{p_end}
{phang2}{cmd:. rdsampsi demvoteshfor2 demmv, tau(5) beta(0.9) all samph(18 19) nratio(0.5)}{p_end}

{pstd}
Power function plot with default options{p_end}
{phang2}{cmd:. rdsampsi demvoteshfor2 demmv, tau(5) plot}{p_end}

{pstd}
Power function plot with user-specified range and step{p_end}
{phang2}{cmd:. rdsampsi demvoteshfor2 demmv, tau(5) plot graph_range(0 800) graph_step(200)}{p_end}

{pstd}
Power function plot with user-specified options{p_end}
{phang2}{cmd:. rdsampsi demvoteshfor2 demmv, tau(5) plot graph_range(0 800) graph_step(200) graph_options(title(Power function) xtitle(sample size) ytitle(power) graphregion(fcolor(white)))}{p_end}


{marker stored_results}{...}
{title:Stored results}

{pstd}{cmd:rdsampsi} stores the following in {cmd:r()}:

{synoptset 20 tabbed}{...}
{p2col 5 20 24 2: Scalars}{p_end}
{synopt:{cmd:r(alpha)}}significance level{p_end}
{synopt:{cmd:r(beta)}}desired power{p_end}
{synopt:{cmd:r(tau)}}desired effect{p_end}
{synopt:{cmd:r(samph_l)}}bandwidth to the left of the cutoff{p_end}
{synopt:{cmd:r(samph_h)}}bandwidth to the right of the cutoff{p_end}
{synopt:{cmd:r(var_l)}}robust bias-corrected variance to the left of the cutoff{p_end}
{synopt:{cmd:r(var_r)}}robust bias-corrected variance to the right of the cutoff{p_end}
{synopt:{cmd:r(bias_l)}}bias to the left of the cutoff{p_end}
{synopt:{cmd:r(bias_r)}}bias to the right of the cutoff{p_end}
{synopt:{cmd:r(N_h_l)}}sample size in bandwidth to the left of the cutoff for variance calculation{p_end}
{synopt:{cmd:r(N_h_r)}}sample size in bandwidth to the right of the cutoff for variance calculation{p_end}
{synopt:{cmd:r(N_l)}}sample size to the left of the cutoff for variance calculation{p_end}
{synopt:{cmd:r(N_r)}}sample size to the right of the cutoff for variance calculation{p_end}
{synopt:{cmd:r(sampsi_tot)}}implied total sample size using robust bias-
corrected standard error{p_end}
{synopt:{cmd:r(sampsi_h_l)}}sample size to the left of the cutoff using robust
bias-corrected standard error{p_end}
{synopt:{cmd:r(sampsi_h_r)}}sample size to the right of the cutoff using
robust bias-corrected standard error{p_end}
{synopt:{cmd:r(sampsi_h_tot)}}sample size inside the window using robust bias-
corrected standard error{p_end}
{synopt:{cmd:r(var_l_cl)}}conventional variance to the left of the cutoff{p_end}
{synopt:{cmd:r(var_r_cl)}}conventional variance to the right of the cutoff{p_end}
{synopt:{cmd:r(sampsi_tot_cl)}}implied total sample size using conventional
standard error{p_end}
{synopt:{cmd:r(sampsi_h_l_cl)}}sample size to the left of the cutoff using
conventional standard error{p_end}
{synopt:{cmd:r(sampsi_h_r_cl)}}sample size to the right of the cutoff using
conventional standard error{p_end}
{synopt:{cmd:r(sampsi_h_tot_cl)}}sample size inside the window using
conventional standard error{p_end}
{synopt:{cmd:r(no_iter)}}number of iterations until convergence of the Newton-Raphson algorithm{p_end}
{synopt:{cmd:r(init_cond)}}initial condition of the Newton-Raphson algorithm{p_end}


{marker refs}{...}
{title:References}

{phang}
Calonico, S., M. D. Cattaneo, and M. H. Farrell. 2018. On the effect of bias
estimation on coverage accuracy in nonparametric inference. 
{it:Journal of the American Statistical Association} 113: 767-779.

{phang}
Calonico, S., M. D. Cattaneo, M. H. Farrell, and R. Titiunik. 2017.
{browse "https://www.stata-journal.com/article.html?article=st0366_1":rdrobust: Software for regression-discontinuity designs}.
{it:Stata Journal} 17: 372-404.{p_end}

{phang}
Calonico, S., M. D. Cattaneo, and R. Titiunik. 2014. {browse "http://www.stata-journal.com/article.html?article=st0366":Robust data-driven inference in the regression-discontinuity design}.
{it:Stata Journal} 14: 909-946.

{phang}
Cattaneo, M. D., B. R. Frandsen, and R. Titiunik. 2015. Randomization
inference in the regression discontinuity design: An application to party
advantages in the U.S. Senate.  {it:Journal of Causal Inference} 3: 1-24.

{phang}
Cattaneo, M. D., R. Titiunik, and G. Vazquez-Bare. 2019.
{browse "https://doi.org/10.1177/1536867X19830919":Power calculations for regression-discontinuity designs}.
{it:Stata Journal} 19: 210-245.


{marker authors}{...}
{title:Authors}

{pstd}
Matias D. Cattaneo{break}
University of Michigan{break}
Ann Arbor, MI{break}
{browse "mailto:cattaneo@umich.edu":cattaneo@umich.edu}

{pstd}
Roc{c i'}o Titiunik{break}
University of Michigan{break}
Ann Arbor, MI{break}
{browse "mailto:titiunik@umich.edu":titiunik@umich.edu}

{pstd}
Gonzalo Vazquez-Bare{break}
University of California, Santa Barbara{break}
Santa Barbara, CA{break}
{browse "mailto:gvazquez@econ.ucsb.edu":gvazquez@econ.ucsb.edu}


{marker also_see}{...}
{title:Also see}

{p 4 14 2}
Article:  {it:Stata Journal}, volume 19, number 1: {browse "https://doi.org/10.1177/1536867X19830919":st0554}{p_end}
